Overview

Type: feature

Summary:
Adds a linear fog mode with explicit start/end distance parameters to the 3D renderer. The existing exponential fog (ConfigureFog) remains backward compatible. Linear fog allows precise control over where fog begins and ends, which is critical for games with varying camera distances.

Related Issues: Closes #631

Changes Made

Engine Core (goud_engine/src/)

• Added FogMode enum (Exponential { density } | Linear { start, end }) in renderer3d/types.rs
• Replaced density: f32 field in FogConfig with mode: FogMode
• Added helper methods (mode_int(), density(), start(), end()) for shader uniform upload
• Updated all OpenGL (GLSL) and WGSL shaders with linear fog branch and division-by-zero guard
• Added fog_mode, fog_start, fog_end uniform locations to MainUniforms and GridUniforms

FFI Layer (goud_engine/src/ffi/)

• Added goud_renderer3d_configure_fog_linear(context_id, enabled, start_distance, end_distance, r, g, b) FFI function
• Updated existing goud_renderer3d_configure_fog to use FogMode::Exponential internally

C# SDK (sdks/csharp/)

• Generated ConfigureFogLinear method in GoudGame.g.cs and NativeMethods.g.cs

Python SDK (sdks/python/)

• Generated configure_fog_linear in _game.py and _ffi.py

TypeScript SDK (sdks/typescript/)

• Node napi binding changes
• Web WASM binding changes
• Type definition changes
• Tests updated

Codegen Pipeline (codegen/)

• Schema changes (configureFogLinear method added)
• Generator changes
• Validator changes
• ffi_mapping changes (goud_renderer3d_configure_fog_linear mapped)

Proc Macros (goud_engine_macros/)

• #[goud_api] attribute changes
  No changes

Tools (tools/)

• lint-layers changes
  No changes

WASM (goud_engine/src/wasm/)

• wasm-bindgen exports
• Sprite renderer changes
• Texture loader changes
  No changes

Examples (examples/)

No changes

Documentation

No changes

Architectural Compliance

• Rust-first: All logic lives in Rust; SDKs are thin wrappers
• FFI boundary: New exports use #[no_mangle] extern "C" and #[repr(C)] where needed
• Dependency flow: Imports follow layer hierarchy (down only)
• SDK parity: Changes exposed via FFI are wrapped in C#, Python, AND TypeScript SDKs
• Unsafe discipline: No unsafe block without a // SAFETY: comment
• File size: No file exceeds 500 lines

Testing

• cargo test passes (4873 passed, 0 failed, 26 ignored GPU-context tests)
• cargo clippy -- -D warnings is clean
• cargo fmt --all -- --check passes
• Python SDK tests pass (python3 sdks/python/test_bindings.py) — if SDK changed
• C# SDK tests pass (dotnet test sdks/csharp.tests/) — if SDK changed
• TypeScript SDK tests pass (cd sdks/typescript && npm test) — if TS SDK changed
• Codegen produces consistent output (python3 codegen/validate.py && python3 codegen/validate_coverage.py)
• Pre-commit hooks pass

Code Quality

• No todo!() or unimplemented!() in production code
• No #[allow(unused)] without justification comment
• Error handling uses Result, not unwrap()/expect() in library code
• Public items have doc comments

Documentation

• Updated relevant AGENTS.md files (if architecture changed)
• Updated README.md (if user-facing behavior changed)
• Added or updated doc comments on new public APIs

Breaking Changes

None

• API changes: None (additive only — new ConfigureFogLinear function)
• FFI signature changes: None (existing configure_fog unchanged)
• SDK interface changes: None (additive only)

Version Bump

Bump type: minor
Justification: New public API surface (ConfigureFogLinear)

Security

• No new unsafe blocks — or each one has a // SAFETY: comment and is necessary
• No new FFI pointer parameters without null checks
• No new dependencies with known advisories (cargo deny check)
• No secrets or credentials in committed files

Performance

Linear fog adds one shader branch per fragment when fog is enabled. The branch is uniform-driven (same for all fragments in a draw call), so GPU branch prediction handles it efficiently. No allocation changes.

Deployment

• NuGet package version updated (if SDK changed)
• Python package version updated (if SDK changed)
• npm package version updated (if TS SDK changed)
• Native library builds on all targets (macOS, Linux, Windows)

Reviewer Notes

• The WGSL uniform struct layout was extended with 3 new fields (fogMode, fogStart, fogEnd) plus padding. All 8 WGSL struct copies were updated consistently.
• Division-by-zero guard (max(end - start, 0.00001)) prevents undefined behavior when start == end.
• The existing OpenGL grid shader uses simple exp(-d*dist) while main shaders use exp(-(d*dist)^2) — this pre-existing inconsistency was preserved.